Incidents API

The Incidents API endpoint allows you to query and retrieve security incidents detected by Cyberhaven. This endpoint provides access to policy violations, data exfiltration attempts, and other security events.

Endpoint

POST /api/rest/v1/incidents/list

Request Format

Basic Request

curl -H 'content-type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://$DEPLOYMENT/api/rest/v1/incidents/list \
  -k --data '{}'

Request with Filters

curl -H 'content-type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  https://$DEPLOYMENT/api/rest/v1/incidents/list \
  -k --data '{
    "filters": {
      "resolution_statuses": ["unresolved"],
      "severities": ["high", "critical"],
      "users": ["john.doe@company.com"]
    },
    "page_size": 50,
    "sort_by": "trigger_time",
    "sort_desc": true
  }'

Request Parameters

Filter Parameters

Parameter	Type	Description
`assignees`	array[string]	Filter by assigned users
`category_ids`	array[string]	Filter by category IDs
`category_names`	array[string]	Filter by category names
`content_tags`	array[string]	Filter by content tags
`dataset_ids`	array[string]	Filter by dataset IDs
`dataset_names`	array[string]	Filter by dataset names
`files`	array[string]	Filter by file names
`incident_ids`	array[string]	Filter by specific incident IDs
`incident_reactions`	array[string]	Filter by user reactions
`incident_responses`	array[string]	Filter by system responses
`personal_info`	array[string]	Filter by PII types
`resolution_statuses`	array[string]	Filter by resolution status
`severities`	array[string]	Filter by severity levels
`users`	array[string]	Filter by user emails

Pagination Parameters

Parameter	Type	Description
`page_id`	string	Token for next page
`page_size`	integer	Number of results per page (max 1000, default 50)

Sorting Parameters

Parameter	Type	Description
`sort_by`	string	Field to sort by
`sort_desc`	boolean	Sort in descending order

Sort Fields

Field	Description
`resolution_status`	Sort by resolution status
`severity`	Sort by severity level
`dataset`	Sort by dataset name
`dataset_id`	Sort by dataset ID
`category`	Sort by category name
`category_id`	Sort by category ID
`user`	Sort by user name
`file`	Sort by file name
`personal_info`	Sort by PII column
`incident_response`	Sort by system response
`incident_reactions`	Sort by user reactions
`event_time`	Sort by event timestamp
`assignee`	Sort by assignee

Filter Values

Resolution Statuses

Value	Description
`unresolved`	Incidents requiring attention
`in_progress`	Incidents being investigated
`resolved`	Incidents marked as resolved
`ignored`	Incidents marked as false positives

Severities

Value	Description
`critical`	Critical severity incidents
`high`	High severity incidents
`medium`	Medium severity incidents
`low`	Low severity incidents
`informational`	Informational incidents

Incident Reactions

Value	Description
`none`	No user reaction
`acknowledged`	User acknowledged the incident
`provided_explanation`	User provided explanation
`requested_review`	User requested review
`requested_unblock`	User requested unblock
`warned`	User was warned
`not_applicable`	Not applicable

Incident Responses

Value	Description
`pending`	Response pending
`warning_received`	Warning delivered
`warned`	User was warned
`access_restricted`	Access was blocked
`access_restricted_expired`	Block expired
`access_restricted_rate_limited`	Rate limited block
`access_restricted_removed`	Block removed
`skipped_rate_limited`	Skipped due to rate limit
`skipped_timeout`	Skipped due to timeout
`not_applicable`	Not applicable

Response Format

Response Structure

{
  "incidents": [
    {
      "id": "incident-123",
      "alert_id": "alert-456",
      "assignee": "admin@company.com",
      "category": {
        "id": "cat-789",
        "name": "Financial Data",
        "description": "Financial information protection"
      },
      "dataset": {
        "id": "ds-101",
        "name": "Credit Card Numbers",
        "description": "Credit card data detection"
      },
      "data": {
        "hostname": "laptop-001",
        "local_user_name": "john.doe",
        "path": "/Users/john/Documents/financial.xlsx",
        "file_size": 2048576
      },
      "edge": {
        "source": {
          "location": "endpoint",
          "path": "/Users/john/Documents/financial.xlsx"
        },
        "destination": {
          "location": "cloud_storage",
          "domain": "dropbox.com"
        }
      },
      "event_time": "2024-01-15T10:30:00Z",
      "trigger_time": "2024-01-15T10:30:05Z",
      "response_time": "2024-01-15T10:30:10Z",
      "resolution_status": "unresolved",
      "severity": "high",
      "user": "john.doe@company.com",
      "file": "financial.xlsx",
      "content_tags": ["credit_card", "financial"],
      "personal_info": ["credit_card_number"],
      "incident_response": "access_restricted",
      "incident_reactions": ["acknowledged"],
      "explanation": "User acknowledged the incident"
    }
  ],
  "total": 150,
  "next_page_id": "eyJwYWdlIjoyLCJzaXplIjo1MH0="
}

Response Fields

Field	Type	Description
`incidents`	array[Incident]	Array of incident objects
`total`	integer	Total number of matching incidents
`next_page_id`	string	Token for next page (if available)

Incident Object Fields

Field	Type	Description
`id`	string	Unique incident identifier
`alert_id`	string	Associated alert ID
`assignee`	string	Assigned user email
`category`	object	Policy category information
`dataset`	object	Dataset information
`data`	object	Event data details
`edge`	object	Data flow information
`event_time`	string	When the event occurred
`trigger_time`	string	When the incident was triggered
`response_time`	string	When the response was delivered
`resolution_status`	string	Current resolution status
`severity`	string	Incident severity level
`user`	string	User involved in the incident
`file`	string	File name involved
`content_tags`	array[string]	Content classification tags
`personal_info`	array[string]	PII types detected
`incident_response`	string	System response taken
`incident_reactions`	array[string]	User reactions
`explanation`	string	User-provided explanation

Example Requests

Get All Unresolved Incidents

{
  "filters": {
    "resolution_statuses": ["unresolved"]
  },
  "sort_by": "trigger_time",
  "sort_desc": true
}

Get High Severity Incidents for Specific User

{
  "filters": {
    "severities": ["high", "critical"],
    "users": ["john.doe@company.com"],
    "resolution_statuses": ["unresolved", "in_progress"]
  },
  "page_size": 25
}

Get Incidents by Category

{
  "filters": {
    "category_names": ["Financial Data", "PII"],
    "resolution_statuses": ["unresolved"]
  },
  "sort_by": "severity"
}

Get Incidents with Specific Content Tags

{
  "filters": {
    "content_tags": ["credit_card", "ssn", "passport"],
    "severities": ["high", "critical"]
  }
}

Time Filtering

To filter incidents by time range, use the times_filter parameter:

{
  "filters": {
    "times_filter": {
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-01-31T23:59:59Z"
    }
  }
}

Error Responses

Common Error Codes

Code	Description	Solution
400	Invalid filter parameters	Check filter values and types
401	Authentication failed	Verify access token
403	Insufficient permissions	Contact administrator
500	Internal server error	Contact support

Error Response Format

{
  "error": {
    "code": "INVALID_FILTER",
    "message": "Invalid severity value provided",
    "details": {
      "field": "severities",
      "value": "invalid_severity"
    }
  }
}

Integration Examples

Python Example

import requests
import json

def get_incidents(token, deployment, filters=None):
    url = f"https://{deployment}/api/rest/v1/incidents/list"
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }
    
    payload = {}
    if filters:
        payload['filters'] = filters
    
    response = requests.post(url, headers=headers, json=payload, verify=False)
    return response.json()

# Get unresolved high severity incidents
filters = {
    "resolution_statuses": ["unresolved"],
    "severities": ["high", "critical"]
}

incidents = get_incidents(token, deployment, filters)
print(f"Found {incidents['total']} incidents")

PowerShell Example

$headers = @{
    'Content-Type' = 'application/json'
    'Authorization' = "Bearer $token"
}

$body = @{
    filters = @{
        resolution_statuses = @("unresolved")
        severities = @("high", "critical")
    }
} | ConvertTo-Json -Depth 3

$response = Invoke-RestMethod -Uri "https://$deployment/api/rest/v1/incidents/list" `
    -Method Post -Headers $headers -Body $body

Write-Output "Found $($response.total) incidents"

Best Practices

Use Specific Filters: Apply filters to reduce response size and improve performance
Implement Pagination: Use page_size and next_page_id for large result sets
Sort Results: Use sort_by and sort_desc to get results in desired order
Handle Rate Limits: Implement retry logic with exponential backoff
Monitor Resolution Status: Track incident resolution progress over time

Endpoints API - Query endpoint sensor status
Audit Log API - Access dataflow audit logs
API v2 Incidents - Enhanced incidents API

Endpoint​

Request Format​

Basic Request​

Request with Filters​

Request Parameters​

Filter Parameters​

Pagination Parameters​

Sorting Parameters​

Sort Fields​

Filter Values​

Resolution Statuses​

Severities​

Incident Reactions​

Incident Responses​

Response Format​

Response Structure​

Response Fields​

Incident Object Fields​

Example Requests​

Get All Unresolved Incidents​

Get High Severity Incidents for Specific User​

Get Incidents by Category​

Get Incidents with Specific Content Tags​

Time Filtering​

Error Responses​

Common Error Codes​

Error Response Format​

Integration Examples​

Python Example​

PowerShell Example​

Best Practices​

Related Endpoints​